home *** CD-ROM | disk | FTP | other *** search
/ Merciful 1 / Merciful - Disc 1.iso / software / a / asm_one / asm-onev1.25a.dms / in.adf / Release3.1 / AutoDocs3.1.lha / doc / realtime.doc < prev    next >
Encoding:
Text File  |  1993-08-12  |  13.7 KB  |  464 lines
  1. TABLE OF CONTENTS
  2.  
  3. realtime.library/CreatePlayer
  4. realtime.library/DeletePlayer
  5. realtime.library/ExternalSync
  6. realtime.library/FindConductor
  7. realtime.library/GetPlayerAttrsA
  8. realtime.library/LockRealTime
  9. realtime.library/NextConductor
  10. realtime.library/SetConductorState
  11. realtime.library/SetPlayerAttrs
  12. realtime.library/UnlockRealTime
  13. realtime.library/CreatePlayer                   realtime.library/CreatePlayer
  14.  
  15.    NAME
  16.     CreatePlayerA -- create a player and link it to a conductor. (V37)
  17.     CreatePlayer -- varargs stub for CreatePlayerA(). (V37)
  18.  
  19.    SYNOPSIS
  20.     player = CreatePlayerA(tagList);
  21.     D0                     A0
  22.  
  23.     struct Player *CreatePlayerA(struct TagItem *);
  24.  
  25.     player = CreatePlayer(firstTag, ...);
  26.  
  27.     struct Player *CreatePlayer(Tag, ...);
  28.  
  29.    FUNCTION
  30.     Creates a player structure with the desired attributes.
  31.  
  32.    INPUTS
  33.     tagList - pointer to an array of tags providing optional extra
  34.           parameters, or NULL
  35.  
  36.    TAGS
  37.     PLAYER_Name (STRPTR) - name of the player (generally the
  38.             application's name). Default is no name. (V37)
  39.  
  40.     PLAYER_Hook (struct Hook *) - function to call when time changes
  41.             occur. Default is no function. The Hook is called
  42.             with:
  43.  
  44.                 A0 - address of Hook structure
  45.                 A1 - message, currently pmTime or pmState
  46.                         A2 - address of Player structure
  47.  
  48.             Note that your hook function is not necessarily called
  49.             TICK_FREQ times per second. This is the maximum number
  50.             of times it can be called. (V37)
  51.  
  52.     PLAYER_Priority (BYTE) - priority for the player, from -128 to +127.
  53.             Default is 0. (V37)
  54.  
  55.     PLAYER_Conductor (STRPTR) - name of the conductor to link with. If
  56.             this conductor doesn't exist, it is created
  57.             automatically. If ~0 is passed, creates a private
  58.             conductor. (V37)
  59.  
  60.     PLAYER_Ready (BOOL) - set/clear the "ready" flag. Default is FALSE.
  61.             (V37)
  62.  
  63.     PLAYER_AlarmTime (LONG) - sets this player's alarm time, and the
  64.             PLAYERF_ALARMSET flag. (V37)
  65.  
  66.     PLAYER_Alarm (BOOL) - if TRUE sets the PLAYERF_ALARMSET flag, FALSE
  67.             clears the flag. Default is FALSE. (V37)
  68.  
  69.     PLAYER_AlarmSigTask (struct Task *) - task to signal on notify or
  70.             alarm. Default is no task. Having no task automatically
  71.             forces the PLAYERF_ALARMSET flag off. (V37)
  72.  
  73.     PLAYER_AlarmSigBit (BYTE) - signal bit to use on alarm or -1 to
  74.             disable. Default is -1. Having a signal bit of -1
  75.             automatically forces the PLAYERF_ALARMSET flag
  76.             off. (V37)
  77.  
  78.     PLAYER_Quiet (BOOL) - when TRUE, this player is ignored. Mainly
  79.             used by external sync applications. Default is FALSE.
  80.             (V37)
  81.  
  82.     PLAYER_UserData (VOID *) - sets the player's UserData value.
  83.             Default is NULL. (V37)
  84.  
  85.     PLAYER_ID (UWORD) - sets the player's ID value. Default is 0. (V37)
  86.  
  87.     PLAYER_Conducted (BOOL) - if TRUE sets the PLAYERF_CONDUCTED flag,
  88.             FALSE clears the flag. Default is FALSE. (V37)
  89.  
  90.     PLAYER_ExtSync (BOOL) - if TRUE, attempts to become external sync
  91.             source. (V37)
  92.  
  93.     PLAYER_ErrorCode (LONG *) - optional pointer to a longword which
  94.             will receive an error code whenever this function
  95.             fails. Possible error values currently include:
  96.               RTE_NOMEMORY - memory allocation failed
  97.               RTE_NOTIMER  - timer (CIA) allocation failed
  98.  
  99.    RESULTS
  100.     player - a pointer to a Player structure on success or NULL on
  101.          failure. When NULL is returned, an error code can be returned
  102.          in the longword variable pointed to by the optional
  103.          PLAYER_ErrorCode tag.
  104.  
  105.    SEE ALSO
  106.     DeletePlayer(), GetPlayerAttrs(), SetPlayerAttrs()
  107.  
  108. realtime.library/DeletePlayer                   realtime.library/DeletePlayer
  109.  
  110.    NAME
  111.     DeletePlayer -- delete a player. (V37)
  112.  
  113.    SYNOPSIS
  114.     DeletePlayer(player);
  115.                  A0
  116.  
  117.     VOID DeletePlayer(struct Player *);
  118.  
  119.    FUNCTION
  120.     Deletes the specified player.
  121.  
  122.     Flushes the conductor that the player was connected to if this
  123.     is the last player connected to that conductor.
  124.  
  125.    INPUTS
  126.     player - Player structure to delete, as allocated by
  127.          CreatePlayer(). May be NULL, in which case this function
  128.          does nothing.
  129.  
  130.    SEE ALSO
  131.     CreatePlayer()
  132.  
  133. realtime.library/ExternalSync                   realtime.library/ExternalSync
  134.  
  135.    NAME
  136.     ExternalSync -- provide external source clock for a player's
  137.             conductor. (V37)
  138.  
  139.    SYNOPSIS
  140.     result = ExternalSync(player, minTime, maxTime);
  141.     D0              A0      D0       D1
  142.  
  143.     BOOL ExternalSync(struct Player *, LONG, LONG);
  144.  
  145.    FUNCTION
  146.     Allows external applications to constrain conductor time between
  147.     minTime and maxTime, with the restraint that time can never run
  148.     backwards. Does nothing if the given player is not the
  149.     current External Sync source.
  150.  
  151.    INPUTS
  152.     player - player referencing the conductor to change
  153.     minTime, maxTime - time constraints
  154.  
  155.    RESULTS
  156.     result - TRUE if everything went OK, FALSE if the player is not the
  157.          current sync source or there is no conductor for the player.
  158.  
  159. realtime.library/FindConductor                 realtime.library/FindConductor
  160.  
  161.    NAME
  162.     FindConductor -- find a conductor by name. (V37)
  163.  
  164.    SYNOPSIS
  165.     conductor = FindConductor(name);
  166.     D0              A0
  167.  
  168.     struct Conductor *FindConductor(STRPTR);
  169.  
  170.    FUNCTION
  171.     Returns the conductor with the given name or NULL if not found.
  172.  
  173.     The conductor list must be locked before calling this function. This
  174.     is done by calling LockRealTime(RT_CONDUCTORS).
  175.  
  176.    INPUTS
  177.     name - name of conductor to find.
  178.  
  179.    RESULTS
  180.     conductor - pointer to a Conductor structure, or NULL if not found.
  181.  
  182.    SEE ALSO
  183.     NextConductor(), LockRealTime(), UnlockRealTime()
  184.  
  185. realtime.library/GetPlayerAttrsA             realtime.library/GetPlayerAttrsA
  186.  
  187.    NAME
  188.     GetPlayerAttrsA -- get the attributes of a player. (V37)
  189.     GetPlayerAttrs -- varargs stub for GetPlayerAttrsA(). (V37)
  190.  
  191.    SYNOPSIS
  192.     numProcessed = GetPlayerAttrsA(player, tagList);
  193.     D0                             A0      A1
  194.  
  195.     ULONG GetPlayerAttrsA(struct Player *, struct TagItem *);
  196.  
  197.     numProcessed = GetPlayerAttrs(player, firstTag, ...);
  198.  
  199.     ULONG GetPlayerAttrs(struct Player *, Tag, ...);
  200.  
  201.    FUNCTION
  202.     Retrieves the attributes of the specified player, according to the
  203.     attributes chosen in the tag list. For each entry in the tag list,
  204.     ti_Tag identifies the attribute, and ti_Data is a pointer to
  205.     the longword variable where you wish the result to be stored.
  206.  
  207.    INPUTS
  208.     player - pointer to the player in question. May be NULL, in which case
  209.              this function returns 0
  210.     tagList - pointer to TagItem list.
  211.  
  212.    TAGS
  213.     PLAYER_Name (STRPTR) - return the name of the player, or NULL
  214.             if this is an unnamed player. (V37)
  215.  
  216.     PLAYER_Hook (struct Hook *) - returns a pointer to the current
  217.             function called when time changes occur, or NULL
  218.             if no function is currently installed. (V37)
  219.  
  220.     PLAYER_Priority (BYTE) - returns the priority for the player. (V37)
  221.  
  222.     PLAYER_Conductor (STRPTR) - returns the name of the conductor this
  223.             player is currently linked with, or NULL if the
  224.             player is not linked to a conductor. (V37)
  225.  
  226.     PLAYER_Ready (BOOL) - gets the state of the "ready" flag. (V37)
  227.  
  228.     PLAYER_AlarmTime (LONG) - gets the current alarm time for this
  229.             player. (V37)
  230.  
  231.     PLAYER_Alarm (BOOL) - returns TRUE if this player's alarm is
  232.             currently on. (V37)
  233.  
  234.     PLAYER_AlarmSigTask (struct Task *) - returns a pointer to the task to
  235.             signal on notify or alarm, or NULL if there is no
  236.             task to signal. (V37)
  237.  
  238.     PLAYER_AlarmSigBit (BYTE) - returns the signal bit to use on alarm or
  239.             -1 if no signal. (V37)
  240.  
  241.     PLAYER_Quiet (BOOL) - returns TRUE if this player is currently being
  242.             ignored. FALSE if not. (V37)
  243.  
  244.     PLAYER_UserData (VOID *) - returns the current value of this player's
  245.             UserData. (V37)
  246.  
  247.     PLAYER_ID (UWORD) - gets the value of this player's ID. (V37)
  248.  
  249.     PLAYER_Conducted (BOOL) - returns TRUE if this player is currently
  250.             being conducted. (V37)
  251.  
  252.     PLAYER_ExtSync (BOOL) - returns TRUE if this player is the current
  253.             external sync source. (V37)
  254.  
  255.    RESULTS
  256.     numProcessed - the number of attributes successfully filled in.
  257.  
  258.    SEE ALSO
  259.     CreatePlayer(), SetPlayerAttrs()
  260.  
  261. realtime.library/LockRealTime                   realtime.library/LockRealTime
  262.  
  263.    NAME
  264.     LockRealTime -- prevent other tasks from changing internal structures.
  265.             (V37)
  266.  
  267.    SYNOPSIS
  268.     lockHandle = LockRealTime(lockType);
  269.     D0                        D0
  270.  
  271.     APTR LockRealTime(ULONG);
  272.  
  273.    FUNCTION
  274.     This routine will lock the internal sempahores in the RealTime library.
  275.     If they are already locked by another task, this routine will wait
  276.     until they are free.
  277.  
  278.    INPUTS
  279.     lockType - the internal list to lock. Only RT_CONDUCTORS is
  280.            currently defined.
  281.  
  282.    RESULT
  283.     handle - if lockType is valid, returns a value that must be passed
  284.          later to UnlockRealTime() to unlock the list. Returns NULL
  285.          if passed an invalid lock type.
  286.  
  287.    SEE ALSO
  288.     UnlockRealTime()
  289.  
  290. realtime.library/NextConductor                 realtime.library/NextConductor
  291.  
  292.    NAME
  293.     NextConductor -- return the next conductor on realtime.library's
  294.              conductor list. (V37)
  295.  
  296.    SYNOPSIS
  297.     conductor = NextConductor(previousConductor);
  298.     D0              A0
  299.  
  300.     struct Conductor *NextConductor(struct Conductor *);
  301.  
  302.    FUNCTION
  303.     Returns the next conductor on realtime.library's conductor list. If
  304.     previousConductor is NULL, returns the first conductor in the list.
  305.     Returns NULL if no more conductors.
  306.  
  307.     The conductor list must be locked before calling this function. This
  308.     is done by calling LockRealTime(RT_CONDUCTORS).
  309.  
  310.    INPUTS
  311.     previousConductor - previous conductor or NULL to get first conductor.
  312.  
  313.    RESULTS
  314.     conductor - next conductor on the list, or NULL if no more.
  315.  
  316.    SEE ALSO
  317.     FindConductor(), LockRealTime(), UnlockRealTime()
  318.  
  319. realtime.library/SetConductorState         realtime.library/SetConductorState
  320.  
  321.    NAME
  322.     SetConductorState -- change the play state of a player's
  323.                  conductor. (V37)
  324.  
  325.    SYNOPSIS
  326.     result = SetConductorState(player, state, time);
  327.     D0               A0       D0     D1
  328.  
  329.     LONG SetConductorState(struct Player *, ULONG, LONG);
  330.  
  331.    FUNCTION
  332.     Changes the play state of the conductor referenced by the
  333.     player. The states can be CONDSTATE_STOPPED, CONDSTATE_PAUSED,
  334.     CONDSTATE_LOCATE, CONDSTATE_RUNNING, or the special value
  335.     CONDSTATE_METRIC which asks the highest priority conducted node
  336.     to do a CONDSTATE_LOCATE, or the special value CONDSTATE_SHUTTLE
  337.     which informs the players that the clock value is changing, but the
  338.     clock isn't actually running. Note that going from CONDSTATE_PAUSED
  339.     to CONDSTATE_RUNNING does not reset the cdt_ClockTime of the
  340.     conductor.
  341.  
  342.    INPUTS
  343.     player - player referencing the conductor to change
  344.     state - new play state of conductor
  345.     time - start time offset in realtime.library heartbeat units
  346.  
  347.    RESULTS
  348.     result - 0 if everything went OK, or a realtime.library error code
  349.          if an error occured. These currently include RTE_PLAYING
  350.          and RTE_NOCONDUCTOR.
  351.  
  352. realtime.library/SetPlayerAttrs               realtime.library/SetPlayerAttrs
  353.  
  354.    NAME
  355.     SetPlayerAttrsA -- set the attributes of a player. (V37)
  356.     SetPlayerAttrs -- varargs stub for SetPlayerAttrsA(). (V37)
  357.  
  358.    SYNOPSIS
  359.     result = SetPlayerAttrsA(player, tagList);
  360.     D0                       A0      A1
  361.  
  362.     BOOL SetPlayerAttrsA(struct Player *, struct TagItem *);
  363.  
  364.     result = SetPlayerAttrs(player,firstTag, ...);
  365.  
  366.     BOOL SetPlayerAttrs(struct Player *, Tag, ...);
  367.  
  368.    FUNCTION
  369.     Changes the attributes of the specified player, according to the
  370.     attributes chosen in the tag list. If an attribute is not provided
  371.     in the tag list, its value remains unchanged.
  372.  
  373.    INPUTS
  374.     player - player to set the attributes of.
  375.     tagList - pointer to an array of tags specifying the attributes
  376.           to change, or NULL.
  377.  
  378.    TAGS
  379.     PLAYER_Name (STRPTR) - name of the player (generally the
  380.             application's name). (V37)
  381.  
  382.     PLAYER_Hook (struct Hook *) - function to call when time changes
  383.             occur. The Hook is called
  384.             with:
  385.  
  386.                 A0 - address of Hook structure
  387.                 A1 - message, currently pmTime or pmState
  388.                         A2 - address of Player structure
  389.  
  390.             Note that your hook function is not necessarily called
  391.             TICK_FREQ times per second. This is the maximum number
  392.             of times it can be called. (V37)
  393.  
  394.     PLAYER_Priority (BYTE) - priority for the player, from -128 to +127.
  395.             (V37)
  396.  
  397.     PLAYER_Conductor (STRPTR) - name of the conductor to link with. If
  398.             NULL, delink from conductor. (V37)
  399.  
  400.     PLAYER_Ready (BOOL) - set/clear the "ready" flag. (V37)
  401.  
  402.     PLAYER_AlarmTime (LONG) - sets this player's alarm time, and the
  403.             PLAYERF_ALARMSET flag. (V37)
  404.  
  405.     PLAYER_Alarm (BOOL) - if TRUE sets the PLAYERF_ALARMSET flag, FALSE
  406.             clears the flag. (V37)
  407.  
  408.     PLAYER_AlarmSigTask (struct Task *) - task to signal on notify or
  409.             alarm. Setting this to NULL automatically clears the
  410.             PLAYERF_ALARMSET flag. (V37)
  411.  
  412.     PLAYER_AlarmSigBit (BYTE) - signal bit to use on alarm or -1 to
  413.             disable. Setting this to -1 automatically clears the
  414.             PLAYERF_ALARMSET. (V37)
  415.  
  416.     PLAYER_Quiet (BOOL) - when TRUE, this player is ignored. Mainly
  417.             used by external sync applications. (V37)
  418.  
  419.     PLAYER_UserData (VOID *) - sets this player's UserData value. (V37)
  420.  
  421.     PLAYER_ID (UWORD) - sets this player's ID value. (V37)
  422.  
  423.     PLAYER_Conducted (BOOL) - if TRUE sets the PLAYERF_CONDUCTED flag,
  424.             FALSE clears the flag. (V37)
  425.  
  426.     PLAYER_ExtSync (BOOL) - if TRUE, attempt to become external sync
  427.             source. If FALSE, release external sync. (V37)
  428.  
  429.     PLAYER_ErrorCode (LONG *) - optional pointer to a longword which
  430.             will receive an error code whenever this function
  431.             fails. Possible error values currently include:
  432.               RTE_NOMEM   - memory allocation failed
  433.               RTE_NOTIMER - timer (CIA) allocation failed
  434.  
  435.    RESULTS
  436.     result - TRUE if all went well, FALSE if there was an error.
  437.          When an error occurs, an error code can be returned
  438.          in the longword variable pointed to by the optional
  439.          PLAYER_ErrorCode tag.
  440.  
  441.    SEE ALSO
  442.     CreatePlayer(), DeletePlayer(), GetPlayerAttrs()
  443.  
  444. realtime.library/UnlockRealTime               realtime.library/UnlockRealTime
  445.  
  446.    NAME
  447.     UnlockRealTime -- unlock internal lists. (V37)
  448.  
  449.    SYNOPSIS
  450.     UnlockRealTime(lockHandle);
  451.                    A0
  452.  
  453.     VOID UnlockRealTime(APTR);
  454.  
  455.    FUNCTION
  456.     Undoes the effects of LockRealTime().
  457.  
  458.    INPUTS
  459.     lockHandle - value returned by LockRealTime(). May be NULL.
  460.  
  461.    SEE ALSO
  462.     LockRealTime()
  463.  
  464.